home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / a_man / cat7 / ds.z / ds
Encoding:
Text File  |  2002-10-03  |  17.5 KB  |  397 lines
  1.  
  2.  
  3.  
  4. DDDDSSSS((((7777MMMM))))                                                                  DDDDSSSS((((7777MMMM))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ds - generic (user mode) SCSI driver
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      /dev/scsi/*
  13.  
  14. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  15.      The _d_s interface provides user-mode access to the SCSI bus.  It supports
  16.      the programming interfaces described in _d_s_l_i_b(3) and below.
  17.  
  18.      All of the _d_s devices support the same general interface.  The program
  19.      calls _o_p_e_n, gaining exclusive use of a specified SCSI device (that is,
  20.      two processes may not both have the same device open at the same time via
  21.      this driver).  Additionally, when the OOOO____EEEEXXXXCCCCLLLL open flag set, exclusive use
  22.      of the target will be acquired.  No other SCSI driver will be able to use
  23.      the target until it is closed.  If some other process has the target
  24.      device open from another SCSI driver, the open will fail with errno set
  25.      to EEEEBBBBUUUUSSSSYYYY.  More than one process may in fact have the same target open
  26.      via this driver, if one is a descendent of the other (via _s_p_r_o_c(2) or
  27.      _f_o_r_k(2).  In this case, it is the responsibility of the program(s) to
  28.      ensure that both processes do not both attempt to do commands at the same
  29.      time.
  30.  
  31.      After opening, _i_o_c_t_l calls can be made.  They will either be performed
  32.      directly or turned into SCSI transactions.  Finally, the _c_l_o_s_e call
  33.      releases the device for further use.
  34.  
  35.      The critical interface definitions (request structure and codes, return
  36.      codes, etc.) are defined in <_s_y_s/_d_s_r_e_q._h>.  In particular, most SCSI
  37.      transactions are performed using the _d_s_r_e_q structure:
  38.  
  39.        typedef struct dsreq {        /* DEVSCSI ioctl structure      */
  40.  
  41.                                      /* devscsi prefix ...........   */
  42.          uint          ds_flags;     /* see DSRQ_* flags below       */
  43.          uint          ds_time;      /* timeout in milliseconds
  44.                                         (1 HZ used if zero)          */
  45.          __psint_t     ds_private;   /* private use by caller        */
  46.  
  47.                                      /* SCSI request .............   */
  48.          caddr_t       ds_cmdbuf;    /* command buffer               */
  49.          uchar_t       ds_cmdlen;    /* command buffer length        */
  50.          caddr_t       ds_databuf;   /* data buffer start            */
  51.          uint          ds_datalen;   /* total data length            */
  52.          caddr_t       ds_sensebuf;  /* sense buffer                 */
  53.          uchar_t       ds_senselen;  /* sense buffer length          */
  54.  
  55.                                      /* scatter-gather, etc. .....   */
  56.          dsiovec_t    *ds_iovbuf;    /* scatter-gather dma control   */
  57.          ushort        ds_iovlen;    /* length of scatter-gather     */
  58.          struct dsreq *ds_link;      /* for linked requests          */
  59.          ushort        ds_synch;     /* synchronous transfer control */
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDSSSS((((7777MMMM))))                                                                  DDDDSSSS((((7777MMMM))))
  71.  
  72.  
  73.  
  74.          uchar_t       ds_revcode;   /* devscsi version code         */
  75.  
  76.                                      /* return portion ...........   */
  77.          uchar_t       ds_ret;       /* devscsi return code          */
  78.          uchar_t       ds_status;    /* status byte value            */
  79.          uchar_t       ds_msg;       /* message byte value           */
  80.          uchar_t       ds_cmdsent;   /* actual length command        */
  81.          uint          ds_datasent;  /* actual length user data      */
  82.          uchar_t       ds_sensesent; /* actual length sense data     */
  83.        } dsreq_t;
  84.  
  85.  
  86.      The first two parts of the structure (devscsi prefix, SCSI request) must
  87.      be filled in by the calling program.  The third part (scatter-gather,
  88.      etc.) is largely optional, and the last part (return portion) is used
  89.      only for returned information.
  90.  
  91.      Normally, the _d_s__d_a_t_a* fields are used to control data transmission.  In
  92.      this mode, all sent (received) data uses a single I/O buffer.  If
  93.      desired, however, the _d_s__i_o_v* fields may be used (see DSRQ_IOV) to
  94.      support a set of I/O buffers.  The number of scatter gather entries
  95.      supported is given by the V_MAX define, and is currently 1.  The
  96.      scatter-gather structure, _d_s_i_o_v_e_c__t, is defined as follows:
  97.  
  98.        typedef struct dsiovec {  /* DEVSCSI scatter-gather control   */
  99.            caddr_t  iov_base;    /* i/o base */
  100.            int     iov_len;     /* i/o length */
  101.        } dsiovec_t;
  102.  
  103.  
  104.      Different /_d_e_v/_s_c_s_i implementations will support different subsets of the
  105.      specification.  Items in the following tables are therefore marked to
  106.      indicate the likelihood of support:
  107.  
  108.         !  required  (must be supported)
  109.         .  normal    (usually supported)
  110.         ?  unusual   (seldom  supported)
  111.  
  112. IIIIOOOOCCCCTTTTLLLLSSSS,,,, EEEETTTTCCCC....
  113.      Several _i_o_c_t_ls are supported by /dev/scsi:
  114.  
  115.      DS_ENTER     struct dsreq     !  enter a request
  116.  
  117.      DS_CANCEL    struct dsreq     ?  cancel a request
  118.      DS_POLL      struct dsreq     ?  sample a request
  119.      DS_CONTIN    struct dsreq     ?  continue a request
  120.  
  121.      DS_RESET     uint             .  obsolete -- see scsiha(7M)
  122.  
  123.      DS_SET       uint             !  set permanent flags
  124.      DS_CLEAR     uint             !  clear permanent flags
  125.      DS_GET       uint             !  get permanent flags
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDSSSS((((7777MMMM))))                                                                  DDDDSSSS((((7777MMMM))))
  137.  
  138.  
  139.  
  140.      DS_CONF      struct dsconf    !  get configuration data
  141.      DS_ABORT     uint             .  send abort message
  142.  
  143.  
  144.      The DS_ENTER _i_o_c_t_l is the basis for most interaction with the driver.
  145.      The user program prepares a request structure, issues the _i_o_c_t_l, and
  146.      examines the returned status information.
  147.  
  148.      Other _i_o_c_t_ls help to fill out the interface, however.  The polled I/O
  149.      _i_o_c_t_ls (DS_CANCEL, DS_POLL, DS_CONTIN) are for support asynchronous
  150.      /dev/scsi operations (not in the SCSI sense, but in the I/O sense); these
  151.      are not supported under IRIX.  The DS_ABORT _i_o_c_t_l, provides the ability
  152.      to send an abort message; it is not implemented for all host adapter
  153.      types.  The abort message will be sent only when the target has no
  154.      commands pending, and is therefore useful only to abort immediate mode
  155.      commands, or target specific functions.
  156.  
  157.      The permanent flag _i_o_c_t_ls (DS_SET, DS_GET, DS_CLEAR) allow access to
  158.      internal driver flag bits.  These are undefined, implementation specific,
  159.      and should be avoided if portable code is desired.  The DS_GET ioctl
  160.      returns bits whose definitions begin with DSG_ (from _d_s_r_e_q._h) under IRIX
  161.      5.1.  Not all of the low level host adapter drivers support all (or even
  162.      any) of these bits.
  163.  
  164.      The DS_CONF _i_o_c_t_l, by contrast, allows a user program to detect (and
  165.      perhaps handle) implementation-specific configuration parameters:
  166.  
  167.        typedef struct dsconf {        /* DEVSCSI configuration structure */
  168.                uint dsc_flags;        /* DSRQ flags honored by driver */
  169.                uint dsc_preset;       /* DSRQ flag  preset values */
  170.                u_char dsc_bus;        /* # of this SCSI bus */
  171.                u_char dsc_imax;       /* maximum # of ID's per bus on system */
  172.                u_char dsc_lmax;       /* maximum # of LUN's per ID on system */
  173.                uint dsc_iomax;        /* maximum length of an I/O on this system */
  174.                uint dsc_biomax        /* maximum length of buffered I/O's */
  175.        } dsconf_t;
  176.  
  177.  
  178.      Most of the dsconf members ( _d_s_c__b_u_s, _d_s_c_*_m_a_x) have obvious meanings.
  179.      The _d_s_c__i_o_m_a_x parameter is equivalent to the kernel tunable parameter
  180.      _m_a_x_d_m_a_s_z, except that _d_s_c__i_o_m_a_x is in bytes, rather than pages.  The
  181.      _d_s_c__f_l_a_g_s and _d_s_c__p_r_e_s_e_t words, require more explanation.  They work
  182.      together to indicate how the driver will interpret the DSRQ_* flag bits.
  183.  
  184.      These bits are ORed by the driver with the _d_s__f_l_a_g_s word in _d_s_r_e_q,
  185.      request specific driver actions.  The implementation is then free to
  186.      reject, honor, or ignore them.  Specifically, options will not be turned
  187.      off, but may be rejected via the DSRT_UNIMPL return code.  Options may be
  188.      turned on without any notice whatsoever.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDSSSS((((7777MMMM))))                                                                  DDDDSSSS((((7777MMMM))))
  203.  
  204.  
  205.  
  206.      The _d_s_c__f_l_a_g_s member of _d_s_c_o_n_f indicates which flags the implementation
  207.      promises to honor.  The _d_s_c__p_r_e_s_e_t word indicates, for each flag not
  208.      honored, the value defined by the implementation.  By appropriate logical
  209.      operations, an application may determine which DSRQ_* options are
  210.      actually available.  The action in parentheses is taken when the flag is
  211.      not set.
  212.  
  213.      Note that the DSRQ_SYNXFR and DSRQ_ASYNXFR flags should not be used in
  214.      all commands, only when strictly necessary, as such negotiations are
  215.      relatively expensive.  Not all host adapter drivers will honor these
  216.      flags; for the wd93 host adapter, the default for the _d_s driver is to
  217.      operate in the SCSI bus asynchronous mode.  For other host adapters, the
  218.      default is to operate in synchronous mode and wide mode if it is
  219.      supported by the target.  If necessary, such parameters can usually be
  220.      controlled by editing the master file for the particular host adapter
  221.      driver (i.e. /var/sysgen/master.d/wd95 for wd95,
  222.      /var/sysgen/master.d/scip for scip, etc.).
  223.  
  224.      devscsi options:
  225.  
  226.      DSRQ_ASYNC      ?  no (yes) sleep until request done
  227.      DSRQ_SENSE      .  yes (no) auto get sense on status
  228.      DSRQ_TARGET     ?  target (initiator) role
  229.  
  230.      select options:
  231.  
  232.      DSRQ_SELATN     .  select with (without) atn
  233.      DSRQ_DISC       .  identify disconnect (not) allowed
  234.      DSRQ_SYNXFR     .  attempt SCSI synchronous transfer negotiation
  235.      DSRQ_ASYNXFR    .  attempt SCSI asynchronous transfer negotiation
  236.      DSRQ_SELMSG     .  send supplied (generate) message
  237.  
  238.      data transfer options:
  239.  
  240.      DSRQ_IOV        .  scatter-gather (not) specified
  241.      DSRQ_READ       !  input from SCSI bus
  242.      DSRQ_WRITE      !  output toSCSI bus
  243.      DSRQ_BUF        .  buffered (direct) data transfer
  244.  
  245.      progress/continuation callbacks:
  246.  
  247.      DSRQ_CALL       ?  notify progress (completion-only)
  248.      DSRQ_ACKH       ?  (don't) hold ACK asserted
  249.      DSRQ_ATNH       ?  (don't) hold ATN asserted
  250.      DSRQ_ABORT      ?  abort msg until bus clear
  251.  
  252.      host options (non-portable):
  253.  
  254.      DSRQ_TRACE      .  trace (no) this request
  255.      DSRQ_PRINT      .  print (no) this request
  256.      DSRQ_CTRL1      .  request with host control bit 1
  257.      DSRQ_CTRL2      .  enable driver debug printfs during ioctl
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. DDDDSSSS((((7777MMMM))))                                                                  DDDDSSSS((((7777MMMM))))
  269.  
  270.  
  271.  
  272.                        (if program has superuser privileges)
  273.  
  274.      additional flags:
  275.  
  276.      DSRQ_MIXRDWR    ?  request can both read and write
  277.  
  278. RRRREEEETTTTUUUURRRRNNNN CCCCOOOODDDDEEEESSSS
  279.      The driver has a number of possible return codes, signifying failures on
  280.      the part of the driver, the host SCSI software, or the protocol.  Some
  281.      return codes may be mapped to more generic return codes (DSRT_DEVSCSI,
  282.      DSRT_HOST, DSRT_PROTO).  Note that the _d_s__s_t_a_t_u_s field contains valid
  283.      completion status only when the command completed 'normally'.  On
  284.      timeouts and some other errors, this field is set to 0xff on return to
  285.      indicate that is not valid. The _d_s__r_e_t may be non-zero even if the
  286.      command completed successfully; i.e.  on partial i/o completion, and when
  287.      a request sense has been done.
  288.  
  289.      devscsi software returns:
  290.  
  291.      DSRT_DEVSCSI     !  general devscsi failure
  292.      DSRT_MULT        !  request rejected
  293.      DSRT_CANCEL      !  lower request cancelled
  294.      DSRT_REVCODE     !  software obsolete, must recompile
  295.      DSRT_AGAIN       !  try again, recoverable bus error
  296.      DSRT_UNIMPL      !  unimplemented request option
  297.  
  298.      host SCSI software returns:
  299.  
  300.      DSRT_HOST        !  general host failure
  301.      DSRT_NOSEL       .  no unit responded to select
  302.      DSRT_SHORT       !  incomplete transfer (not an error)
  303.      DSRT_OK          !  completetransfer (no error status)
  304.      DSRT_SENSE       !  cmd w/ status, sense data gotten
  305.      DSRT_NOSENSE     !  cmd w/ status, error getting sense
  306.      DSRT_TIMEOUT     !  request idle longer than requested
  307.      DSRT_LONG        !  target overran data bounds
  308.  
  309.      protocol failures:
  310.  
  311.      DSRT_PROTO       !  misc. protocol failure
  312.      DSRT_EBSY        .  busy dropped unexpectedly
  313.      DSRT_REJECT      .  message reject
  314.      DSRT_PARITY      .  parity error on SCSI bus
  315.      DSRT_MEMORY      .  host memory error
  316.      DSRT_CMDO        .  error during command phase
  317.      DSRT_STAI        .  error during statusphase
  318.  
  319. SSSSUUUUPPPPPPPPOOOORRRRTTTT CCCCOOOODDDDEEEE
  320.      A number of ancillary macros, functions, and data structures are defined
  321.      in <_d_s_l_i_b._h>. While not strictly necessary, these should facilitate the
  322.      task of programming SCSI control programs.
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. DDDDSSSS((((7777MMMM))))                                                                  DDDDSSSS((((7777MMMM))))
  335.  
  336.  
  337.  
  338. AAAADDDDDDDDIIIITTTTIIIIOOOONNNNAAAALLLL IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
  339.      Consult the SCSI standards documents, and the manuals for the device you
  340.      are working with for more information.  The "SCSI 1" specification
  341.      document is called _S_C_S_I _S_p_e_c_i_f_i_c_a_t_i_o_n, _A_N_S_I _X_3_T_9._2/_8_6-_1_0_9. Also of
  342.      interest is the Common Command Set specification document _S_C_S_I _C_C_S
  343.      _S_p_e_c_i_f_i_c_a_t_i_o_n, _A_N_S_I _X_3_T_9._2/_8_5-_3
  344.  
  345. NNNNOOOOTTTTEEEESSSS
  346.      The _d_s programming interface contains a number of optional features.  The
  347.      control program must therefore be able to react properly, should a
  348.      desired function be unavailable.
  349.  
  350.      The peculiarities of any given SCSI device are the responsibility of the
  351.      control program.  The /_d_e_v/_s_c_s_i interface merely allows communication to
  352.      take place.
  353.  
  354.      Since the driver provides direct access to the SCSI bus, the system
  355.      administrator must be very careful in setting up the permissions on the
  356.      device files, lest security holes occur.
  357.  
  358.      No kernel read/write interface is provided, due to the variety of forms
  359.      these commands take in terms of both size and field definitions.
  360.  
  361.      No support currently exists for target mode or asynchronous (polled) I/O.
  362.  
  363.      No checking is currently performed for potentially dangerous actions
  364.      (Copy, ID and code downloading, etc.).
  365.  
  366. NNNNOOOOTTTTEEEE
  367.      The device for each controller, id, lun trio is exclusive open, in that
  368.      once that combination is opened via this interface or the 'normal' system
  369.      interfaces, it may not be opened again, until released by the other user.
  370.      The normal error returned in this case is EBUSY.  The driver is
  371.      semaphored such that multiple copies of the file descriptor may be used,
  372.      either by the same program, or its children via fork, etc.
  373.  
  374. FFFFIIIILLLLEEEESSSS
  375.      ////ddddeeeevvvv////ssssccccssssiiii////sssscccc_c_o_n_t_r_o_l_l_e_r#dddd_t_a_r_g_e_t#llll_l_u_n#
  376.      ////ddddeeeevvvv////ssssccccssssiiii////_n_o_d_e_n_a_m_e////lllluuuunnnn_l_u_n#////cccc_c_o_n_t_r_o_l_l_e_r#pppp_p_o_r_t#
  377.  
  378. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  379.      dslib(3) for discussion of routines to simplify the use of the driver.
  380.      dksc(7M) for a NOTES section describing some configuration options of the
  381.      underlying SCSI driver.
  382.      scsiha(7M) for operations on the entire SCSI bus
  383.      cdintro(3) for discussion of a library above dslib that supports use of
  384.      audio CD's in the CD-ROM drive.
  385.      scsicontrol(1m) for a program that uses this driver to probe and control
  386.      scsi devices.
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.